.\" runpause.8
.\" wcm, 2009.12.11 - 2011.03.11
.\" ===
.TH runpause 8 "January 2013" "runtools-2.07" "runtools"
.SH NAME
runpause \- run a program after a specified delay
.SH SYNOPSIS
.B runpause [\-hV] [\-L
.I label
.B ]
.I secs program
.B [
.I args ...
.B ]
.SH DESCRIPTION
.B runpause
sleeps for
.I secs
(or until interrupted by a signal),
and then runs
.I program
with any arguments given in 
.IR args .
.PP
If
.I secs
is 0,
.B runpause
will pause forever,
or until interrupted by a signal.
.PP
If
.I program
does not contain a ``/'' slash character,
.B runpause
will perform a shell-like search for the executable using the
.B PATH
variable in the current environment.
.SH OPTIONS
.TP
.B \-h
Help.
Print a brief usage message to stderr and exit.
.TP
.B \-L label
Label.
May be used to provide
.I label
as a distinctive command-line marker for an instance of
.BR runpause ,
such as for reference in
.BR ps (1)
listings.
Otherwise, this option has no effect.
.TP
.B \-V
Version.
Print the version number to stderr and exit.
.SH EXAMPLES
The
.B runpause
utility may be used to hack a
.BR perpetrate (5)
service out of what would normally be a system initialization:
.PP
.RS
.nf
#!/bin/sh
exec 2>&1

if test ${1} = 'start' ; then
  # startup network:
  echo "starting network ..."
  ifconfig ...
  # maintain persistent state for this service:
  exec runpause -L network 0 /bin/true
fi

if test ${1} = 'reset' ; then
  # take down network and whatever depends on it:
  echo "resetting network ..."
  ...
fi

### EOF
.fi
.RE
.PP
The author does not recommend this sort of thing
and will never mention it again.
.SH EXIT STATUS
.B runpause
exits with one of the following values:
.TP
0
.I program
was invoked and completed successfully.
In this case,
the exit code is returned by the
.IR program ,
rather than by
.B runpause
itself.
.TP
100
.B runpause
failed because of a usage error,
such as an invalid command\-line option or argument.
In this case,
.B runpause
prints a brief error message and usage help to stderr on exit.
.TP
111
.B runpause
failed due to some system or resource error.
In this case,
.B runpause
prints a brief diagnostic message to stderr on exit.
.TP
1\-127
.I program
was invoked and failed with its own non-zero exit status.
.SH AUTHOR
Wayne Marshall, http://b0llix.net/perp/
.SH SEE ALSO
.nh
.BR runtools_intro (8),
.BR runargs (8),
.BR runargv0 (8),
.BR runchoom (8),
.BR rundetach (8),
.BR rundeux (8),
.BR runenv (8),
.BR runfile (8),
.BR runlimit (8),
.BR runlock (8),
.BR runsession (8),
.BR runtool (8),
.BR runtrap (8),
.BR runuid (8),
.BR perpd (8),
.BR perpetrate (5)
.\" EOF
